docs: split README into docs/, add Related section and a runnable demo - #73
Merged
Merged
Conversation
…e demo README.md drops from 492 to 231 lines: per-harness install detail moves to docs/INSTALL.md, and Configuration/worktrees/opt-out/housekeeping/layout move to docs/REFERENCE.md (which also documents the handoff-as-executable-input trust boundary). Adds a Related section naming 9 verified alternative tools, and a demo/homelab/ fictional project with a real HANDOFF.md, session log, and unconsumed capture buffer, wired via demo/setup.sh so someone can try throughline in under a minute without installing into a real repo. Prompted by a competitive read of adrrr/persistent-handoff, whose README structure (pitch -> demo -> install, reference material pushed to docs/) and named "Related" section this borrows the shape of. Closes #69 Closes #70 Closes #65 Addresses #68 - docs split and demo are done, the recorded demo GIF is not Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UXL2ffVDsAp4P7387Nr18G
…comment /review-pr on PR #73 found four real issues: - demo/homelab/scripts/check-links.sh still sent a HEAD request (curl -I), contradicting the demo's own HANDOFF.md and session log, both of which claim the fix (switch to GET) already landed. - demo/homelab/README.md linked ../README.md, which resolves to a nonexistent demo/README.md - needed ../../README.md. - README.md's OpenCode session-end cross-reference pointed at the README's own (now content-free) #opencode section instead of docs/INSTALL.md#opencode, where the session.idle explanation actually moved to. - demo/homelab/.gitignore's negation comment claimed the root .gitignore's .claude/throughline/ pattern matches at every depth; it doesn't (it's repo-relative), so six negation lines were dead weight and the comment taught something untrue about gitignore anchoring. Removed the no-op lines, corrected the comment. Also: the demo's link-check.log ended at Aug 29 with no third clean night logged, so the walkthrough's own scripted prompt ("update the handoff if the third clean night landed") always resolved to "not yet" - a no-op. Added the Aug 30 clean run so trying the demo as documented produces a real distill. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UXL2ffVDsAp4P7387Nr18G
jsirish
added a commit
that referenced
this pull request
Sep 1, 2026
…rbage /review-pr on PR #74 diffed the days_from_civil awk function against Python's calendar for every date from 1899-01-01 to 2100-12-31 (73,779 dates, zero mismatches) - the arithmetic itself was right - but found the regex extraction only validated that hf_date/commit_date were digit-shaped, not that they were real calendar dates. A hand-edited "**Last Updated:** 2026-00-00" computed a confident wrong answer ("275 day(s) before") instead of the "say nothing when unparseable" this check already promises elsewhere. days() now range-checks month/day/leap-February itself and sets a `bad` flag rather than returning a number for garbage input. Also (same review): `head -20` on `git status -s` bounds live git state's LINE COUNT but not each line's WIDTH - one modified tracked file's path can be arbitrarily long regardless of `head`, and a 20-modified-file monorepo fixture with ~8-segment paths measured over 2KB with nothing bounding it. Since issue #64 moved this block to render first specifically because it was "small and bounded", it needed the same per-line truncation discipline the buffer-tail inline already has. Added TL_GIT_STATUS_LINE_CHARS=200 with the same awk truncation pattern. Also updates CHANGELOG.md (this PR and the already-merged #73 docs/demo/ Related-work PR both landed without an entry) and adds one line to README.md's capture-point table describing the new stale-handoff warning. 3 new test cases (171 -> 174 passing). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UXL2ffVDsAp4P7387Nr18G
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Prompted by a competitive read of
adrrr/persistent-handoff, a new plugin in throughline'sexact problem space (see the linked issues for the full analysis).
housekeeping, and the layout tree move to new
docs/REFERENCE.md. Full per-harness installdetail (requirements, updating, Codex's trust step, OpenCode's local-path install) moves to
new
docs/INSTALL.md. README keeps the pitch, comparison table, capability matrix, andone-liner install commands.
thepushkarp/handoff, REMvisual/claude-handoff, who96/claude-code-context-handoff,
Sting25/claude-code-handoff, blader/baton, rupaut98/unforget, mattpocock/skills), one honest
line each on how they differ.
docs/REFERENCE.mdnow states plainly that a trackedHANDOFF.mdisinput the agent acts on, not passive documentation - anyone who can push to a repo that tracks
it writes into every future session's context.
demo/homelab/is a fictional link-checker with a real investigation historyHANDOFF.md, a prior session log, and a live unconsumed capture buffer - wiredvia a project-scoped
.claude/settings.json.demo/setup.shcopies the real hooks/skills in(gitignored copies, rebuilt fresh, so the demo never drifts from the canonical versions) and
prints a walkthrough.
Recording the actual demo GIF is still open (needs a real terminal session); #68 stays open for
that.
Test plan
sh tests/run.sh: 167/167 pass, no regressionsshellcheck -s bashclean on the two new demo scriptslocal-ci.sh --strict: all 5 checks PASS (shellcheck, manifest validation, plugin versionagreement, hook tests, opencode plugin)
demo/setup.shfor real, then invoked the copiedsession-onboard.shagainstdemo/homelabwith a live payload: correctly injects the HANDOFF.md pointer and flags theunconsumed capture buffer
git add -A --dry-runconfirms only the intended demo files get tracked - copiedhooks/skills,
buffer/archive/, and.capture-errorsstay gitignored as designed#claude-code,#codex-cli, etc.) still resolve afterthe split
Closes #69
Closes #70
Closes #65